Skip to main content

MDX Styling Guide for Docusaurus

MDX allows you to use JSX in your markdown content. You can import components, such as interactive charts or alerts, and embed them within your content. This makes writing interactive documentation with Docusaurus a breeze.

1. Standard Markdown Styling​

Docusaurus supports standard Markdown features.

  • Bold: **bold text** -> bold text
  • Italic: *italic text* -> italic text
  • Links : [Links](https://docusaurus.io)
  • Inline Code : inline code
  • Highlighting: <mark>highlighted</mark> -> highlighted

Lists​

  • Item 1
  • Item 2
    • Sub-item A
    • Sub-item B

2. Admonitions (Alerts)​

Docusaurus has built-in support for admonitions. Use them to highlight important information.

note

This is a note.

tip

This is a tip.

info

This is an info box.

caution

This is a caution warning.

danger

This is a danger alert!

Custom Titles​

Pro Tip

You can add a custom title to admonitions like this.

3. Tabs​

Tabs are useful for showing different variants of code or configuration.

This is an apple 🍎

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="apple" label="Apple" default>
    This is an apple 🍎
  </TabItem>
  ...
</Tabs>

4. Code Blocks​

Syntax Highlighting​

function helloWorld() {
  console.log("Hello, Docusaurus!");
}

Title and Line Highlighting​

src/components/MyComponent.js
function MyComponent() {
  return (
    <div>
      <h1>Hello World</h1>
      <p>This line is highlighted.</p>
    </div>
  );
}

5. Details (Accordion)​

Standard HTML <details> and <summary> work perfectly and are styled by Docusaurus.

Click to expand!

Hidden Content

You found the secret message! 📝

6. React Components​

You can define or import React components directly.

How about some Docusaurus Green or Facebook Blue?

7. Assets (Images & Videos)​

Local Images​

Referencing images in the static folder: ![Description](/img/logo.png)

MDX Images​

You can also use the standard Markdown syntax or HTML for more control: <img src="/img/logo.png" width="200" alt="Docusaurus Logo" />

8. Layout & Micro-interactions​

Dividers​

Use --- for a horizontal rule.

Headings​

Use # through ###### for different levels. Docusaurus automatically generates a Table of Contents (TOC) on the right sidebar.

Badges​

Primary Secondary Success Info Warning Danger

9. Frontmatter & Sidebar Configuration​

Frontmatter is the block of YAML at the top of your markdown files. It controls how the page is treated by Docusaurus.

---
id: my-doc-id
title: Page Title (shows in <title> and <h1>)
sidebar_label: Custom Sidebar Name
sidebar_position: 2
sidebar_class_name: hidden
---

Fixing Stripped Number Prefixes​

Docusaurus automatically strips numbers like 01- or 10. from folder names for sorting. To keep them in the sidebar:

  1. Use sidebar_label in the file's frontmatter.
  2. Or use a _category_.json file inside the folder for group labels:
{
  "label": "01. Setup",
  "position": 1
}

10. Best Practices​

  1. Use MDX extension: Always use .mdx if you plan to use JSX components like Tabs.
  2. Import once: If you use many Tabs, consider adding the import to src/theme/MDXComponents for global availability.
  3. Clarity: Use Admonitions to break up long walls of text.
  4. Consistency: Use the same code block titles and styling throughout your documentation.